ExoPlayer provides functionality to download media for offline playback. In most use cases, it's desirable for downloads to continue even when your app is in the background. For these use cases, your app should subclass DownloadService and send commands to the service to add, remove, and control the downloads. The following diagram shows the main classes that are involved.

To create a DownloadService, subclass it and implement its abstract methods:

Finally, define the service in your AndroidManifest.xml file:

See DemoDownloadService and AndroidManifest.xml in the ExoPlayer demo app for a concrete example.

The following code snippet demonstrates how to instantiate a DownloadManager, which can be returned by getDownloadManager() in your DownloadService:

See DemoUtil in the demo app for a concrete example.

To add a download, create a DownloadRequest and send it to your DownloadService. For adaptive streams, use DownloadHelper to help build a DownloadRequest. The following example shows how to create a download request:

In this example, contentId is a unique identifier for the content. In simple cases, the contentUri can often be used as the contentId, however apps are free to use whatever ID scheme best suits their use case. DownloadRequest.Builder also has some optional setters. For example, setKeySetId and setData can be used to set DRM and custom data that the app wishes to associate with the download, respectively. The content's MIME type can also be specified using setMimeType, as a hint for cases where the content type cannot be inferred from contentUri.

Once created, the request can be sent to the DownloadService to add the download:

In this example, MyDownloadService is the app's DownloadService subclass, and the foreground parameter controls whether the service will be started in the foreground. If your app is already in the foreground, then the foreground parameter should normally be set to false because the DownloadService will put itself in the foreground if it determines that it has work to do.

A download can be removed by sending a remove command to the DownloadService, where contentId identifies the download to be removed:

You can also remove all downloaded data with DownloadService.sendRemoveAllDownloads.

A download will only progress if four conditions are met:

All of these conditions can be controlled by sending commands to your DownloadService.

It's possible to set a reason for one or all downloads being stopped:

stopReason can be any non-zero value (Download.STOP_REASON_NONE = 0 is a special value meaning that the download is not stopped). Apps that have multiple reasons for stopping downloads can use different values to keep track of why each download is stopped. Setting and clearing the stop reason for all downloads works the same way as setting and clearing the stop reason for a single download, except that contentId should be set to null.

When a download has a non-zero stop reason, it will be in the Download.STATE_STOPPED state. Stop reasons are persisted in the DownloadIndex, and so are retained if the application process is killed and later restarted.

All downloads can be paused and resumed as follows:

When downloads are paused, they will be in the Download.STATE_QUEUED state. Unlike setting stop reasons, this approach does not persist any state changes. It only affects the runtime state of the DownloadManager.

Requirements can be used to specify constraints that must be met for downloads to proceed. The requirements can be set by calling DownloadManager.setRequirements() when creating the DownloadManager, as in the example above. They can also be changed dynamically by sending a command to the DownloadService:

When a download cannot proceed because the requirements are not met, it will be in the Download.STATE_QUEUED state. You can query the not met requirements with DownloadManager.getNotMetRequirements().

The maximum number of parallel downloads can be set by calling DownloadManager.setMaxParallelDownloads(). This would normally be done when creating the DownloadManager, as in the example above.

When a download cannot proceed because the maximum number of parallel downloads are already in progress, it will be in the Download.STATE_QUEUED state.

The DownloadIndex of a DownloadManager can be queried for the state of all downloads, including those that have completed or failed. The DownloadIndex can be obtained by calling DownloadManager.getDownloadIndex(). A cursor that iterates over all downloads can then be obtained by calling DownloadIndex.getDownloads(). Alternatively, the state of a single download can be queried by calling DownloadIndex.getDownload().

DownloadManager also provides DownloadManager.getCurrentDownloads(), which returns the state of current (i.e. not completed or failed) downloads only. This method is useful for updating notifications and other UI components that display the progress and status of current downloads.

You can add a listener to DownloadManager to be informed when current downloads change state:

See DownloadManagerListener in the demo app's DownloadTracker class for a concrete example.

Playing downloaded content is similar to playing online content, except that data is read from the download Cache instead of over the network.

To play downloaded content, create a CacheDataSource.Factory using the same Cache instance that was used for downloading, and inject it into DefaultMediaSourceFactory when building the player:

If the same player instance will also be used to play non-downloaded content then the CacheDataSource.Factory should be configured as read-only to avoid downloading that content as well during playback.

Once the player has been configured with the CacheDataSource.Factory, it will have access to the downloaded content for playback. Playing a download is then as simple as passing the corresponding MediaItem to the player. A MediaItem can be obtained from a Download using Download.request.toMediaItem, or directly from a DownloadRequest using DownloadRequest.toMediaItem.

The preceding example makes the download cache available for playback of all MediaItems. You can also make the download cache available for individual MediaSource instances, which can be passed directly to the player:

Adaptive streams (e.g. DASH, SmoothStreaming and HLS) normally contain multiple media tracks. There are often multiple tracks that contain the same content in different qualities (e.g. SD, HD and 4K video tracks). There may also be multiple tracks of the same type containing different content (e.g. multiple audio tracks in different languages).

For streaming playbacks, a track selector can be used to choose which of the tracks are played. Similarly, for downloading, a DownloadHelper can be used to choose which of the tracks are downloaded. Typical usage of a DownloadHelper follows these steps:

Playback of downloaded adaptive content requires configuring the player and passing the corresponding MediaItem, as described above.

When building the MediaItem, MediaItem.playbackProperties.streamKeys must be set to match those in the DownloadRequest so that the player only tries to play the subset of tracks that have been downloaded. Using Download.request.toMediaItem and DownloadRequest.toMediaItem to build the MediaItem will take care of this for you.